\name{phylo.maker}
\alias{phylo.maker}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Make phylogenetic hypothesis for a list of species based on a backbone phylogeny.
}
\description{
This function makes phylogenetic hypotheses for a list of species under three scenarios based on a backbone phylogeny.
}
\usage{
phylo.maker(sp.list, tree, gen.list, nodes.type = 1, output.sp.list = TRUE, output.tree = FALSE, scenario = 3, r = 1)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{sp.list}{An user-provided species list upon which to make the phylogenetic hypotheses.
}
  \item{tree}{The phylogeny of a species group, which is the backbone of making the phylogenetic hypotheses of sp.list.
}
  \item{gen.list}{A data frame with two columns, column one includes the names of all extant genera of a species group, column two includes the names of the families of the genera in column one. The file containing the information can be downloaded online.
}
  \item{nodes.type}{The type of nodes information of the backbone phylogeny selected by the user. The default is 1, which is generated by build.nodes.1 function, the other option is 2, generated by build.nodes.2.
}
  \item{output.sp.list}{Whether or not to output the user-provided species list, with a column added to indicate the status of species of pruning, binding or failing to bind to the backbone phylogeny. The default is TRUE.
}
  \item{output.tree}{Whether or not to output the updated backbone phylogeny, within which the user provided species have been incorporated. The default is FALSE.
}
  \item{scenario}{The scenario under which to make the phylogenetic hypothesis, details can be found in Qian & Jin (2016) and Jin & Qian (2019). The default is 3 (scenario 3), the other options are 1 and 2.
}
 \item{r}{The number of runs set for scenario 2, which follows a randomization procedure of inserting tips into the backbone tree. Each run returns a phylogeny built following this procedure. The default is set as 1, can be set to larger integers, such as 100.
}
}
\details{
%%  ~~ If necessary, more details than the description above ~~
}
\value{
A list of,
  \item{phylo }{The phylogeny of the user specified list of species built under a scenario.}
  \item{species.list }{Optional. The default is TRUE. The user specified list of species with a column at the end indicating of each species status of "prune", "bind" or "fail to bind" to the backbone phylogeny. Specifically, species matched between the species.list and the backbone phylogeny are indicated as "prune"; species absent from the backbone phylogeny, but were successfully binded to the backbone phylogeny are indicated as "bind (genus level) or bind (family level)"; species absent from the backbone phylogeny and failed to be binded to the backbone phylogeny are indicated as  "fail to bind".}
  \item{tree.scenario.1 }{Optional. The backbone phylogeny that has incorporated the species in the user specified species list built under scenario 1.}
  \item{tree.scenario.2 }{Optional. A list of the backbone phylogenies that has incorporated the species in the user specified species list built under scenario 2.}
  \item{tree.scenario.3 }{Optional. The backbone phylogeny that has incorporated the species in the user specified species list built under scenario 3.}
}
\references{
Qian, H. & Jin, Y. (2016) An updated megaphylogeny of plants, a tool for generating plant phylogenies and an analysis of phylogenetic community structure. Journal of Plant Ecology, 9, 233-239.
Jin, Y. & Qian, H. (2019) V.PhyloMaker: an R package that can generate very large phylogenies for vascular plants. Ecography, 42, 1353–1359.
}
\author{
Yi Jin
}
\note{
%%  ~~further notes~~
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }% use one of  RShowDoc("KEYWORDS")
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
